// c06_integer_overflow - 整数溢出：wrapping, checked, saturating
// 深入学习Rust中整数溢出的三种处理策略及其实际应用

fn main() {
    println!("=== Rust 整数溢出处理示例 ===\n");
    
    // 1. 演示默认行为与溢出检测
    demonstrate_default_overflow_behavior();
    
    // 2. Wrapping 环绕模式 - 溢出时从另一端开始
    demonstrate_wrapping_arithmetic();
    
    // 3. Checked 检查模式 - 返回 Option，安全处理
    demonstrate_checked_arithmetic();
    
    // 4. Saturating 饱和模式 - 溢出时保持边界值
    demonstrate_saturating_arithmetic();
    
    // 5. 三种模式的对比分析
    demonstrate_comparison_analysis();
    
    // 6. 实际应用场景演示
    demonstrate_real_world_applications();
    
    // 7. 最佳实践建议
    demonstrate_best_practices();
    
    println!("\n=== 总结 ===");
    println!("✓ Wrapping: 适用于位运算、加密算法等需要模运算的场景");
    println!("✓ Checked: 适用于需要检测溢出错误的关键计算");
    println!("✓ Saturating: 适用于音频、图像处理等需要边界限制的场景");
    println!("根据具体需求选择合适的溢出处理策略，确保程序的安全性和正确性！");
}

/// 演示默认溢出行为与检测方法
fn demonstrate_default_overflow_behavior() {
    println!("1. 默认溢出行为与检测");
    println!("   在Debug模式下，整数溢出会触发panic");
    println!("   在Release模式下，整数溢出会自动wrapping");
    
    // 演示接近边界的计算
    let max_u8 = u8::MAX;  // 255
    let almost_overflow = 254u8;
    
    println!("\n原始值: {} (u8::MAX = {})", almost_overflow, max_u8);
    println!("安全的加法: {} + 1 = {}", almost_overflow, almost_overflow + 1);
    
    // 展示边界值信息
    println!("\n各类型的边界值信息:");
    println!("u8:  {} ~ {}", u8::MIN, u8::MAX);
    println!("i8:  {} ~ {}", i8::MIN, i8::MAX);
    println!("u16: {} ~ {}", u16::MIN, u16::MAX);
    println!("i16: {} ~ {}", i16::MIN, i16::MAX);
    println!("u32: {} ~ {}", u32::MIN, u32::MAX);
    println!("i32: {} ~ {}", i32::MIN, i32::MAX);
    
    println!("   💡 注意：在生产环境中需要显式处理可能的溢出情况");
    println!("==================================================\n");
}

/// 演示 Wrapping 环绕模式
fn demonstrate_wrapping_arithmetic() {
    println!("2. Wrapping 环绕模式 - 溢出时从另一端开始");
    println!("   当计算结果超出类型范围时，会从另一端\"环绕\"继续");
    
    // 无符号整数的wrapping示例
    println!("\n2.1 无符号整数 wrapping 示例:");
    let max_u8 = u8::MAX;  // 255
    let result1 = max_u8.wrapping_add(1);    // 255 + 1 = 0 (环绕)
    let result2 = max_u8.wrapping_add(5);    // 255 + 5 = 4 (环绕)
    
    println!("u8::MAX ({}) + 1 = {} (环绕到0)", max_u8, result1);
    println!("u8::MAX ({}) + 5 = {} (环绕到4)", max_u8, result2);
    
    let min_u8 = u8::MIN;  // 0
    let result3 = min_u8.wrapping_sub(1);    // 0 - 1 = 255 (环绕)
    let result4 = min_u8.wrapping_sub(10);   // 0 - 10 = 246 (环绕)
    
    println!("u8::MIN ({}) - 1 = {} (环绕到255)", min_u8, result3);
    println!("u8::MIN ({}) - 10 = {} (环绕到246)", min_u8, result4);
    
    // 有符号整数的wrapping示例
    println!("\n2.2 有符号整数 wrapping 示例:");
    let max_i8 = i8::MAX;  // 127
    let result5 = max_i8.wrapping_add(1);    // 127 + 1 = -128 (环绕)
    let result6 = max_i8.wrapping_add(10);   // 127 + 10 = -119 (环绕)
    
    println!("i8::MAX ({}) + 1 = {} (环绕到最小值)", max_i8, result5);
    println!("i8::MAX ({}) + 10 = {} (环绕)", max_i8, result6);
    
    let min_i8 = i8::MIN;  // -128
    let result7 = min_i8.wrapping_sub(1);    // -128 - 1 = 127 (环绕)
    let result8 = min_i8.wrapping_sub(5);    // -128 - 5 = 123 (环绕)
    
    println!("i8::MIN ({}) - 1 = {} (环绕到最大值)", min_i8, result7);
    println!("i8::MIN ({}) - 5 = {} (环绕)", min_i8, result8);
    
    // wrapping乘法和除法示例
    println!("\n2.3 wrapping 乘法和其他运算:");
    let large_mult = 200u8.wrapping_mul(2);  // 200 * 2 = 400 -> 144 (400 % 256)
    println!("200u8 * 2 = {} (wrapping: 400 % 256 = 144)", large_mult);
    
    let shift_result = 64u8.wrapping_shl(2);  // 64 << 2 = 256 -> 0
    println!("64u8 << 2 = {} (wrapping: 256 % 256 = 0)", shift_result);
    
    println!("   ✓ Wrapping模式确保运算永远不会panic，适用于位运算和模运算场景");
    println!("==================================================\n");
}

/// 演示 Checked 检查模式
fn demonstrate_checked_arithmetic() {
    println!("3. Checked 检查模式 - 返回 Option，安全处理");
    println!("   返回 Some(结果) 表示成功，None 表示溢出");
    
    println!("\n3.1 checked 加法示例:");
    let max_u8 = u8::MAX;  // 255
    
    match max_u8.checked_add(1) {
        Some(result) => println!("u8::MAX + 1 = {} (成功)", result),
        None => println!("u8::MAX + 1 = None (溢出检测)")
    }
    
    match max_u8.checked_add(0) {
        Some(result) => println!("u8::MAX + 0 = {} (成功)", result),
        None => println!("u8::MAX + 0 = None (溢出检测)")
    }
    
    println!("\n3.2 checked 减法示例:");
    let min_u8 = u8::MIN;  // 0
    
    match min_u8.checked_sub(1) {
        Some(result) => println!("u8::MIN - 1 = {} (成功)", result),
        None => println!("u8::MIN - 1 = None (下溢检测)")
    }
    
    match 10u8.checked_sub(5) {
        Some(result) => println!("10u8 - 5 = {} (成功)", result),
        None => println!("10u8 - 5 = None (下溢检测)")
    }
    
    println!("\n3.3 checked 乘法示例:");
    match 200u8.checked_mul(2) {
        Some(result) => println!("200u8 * 2 = {} (成功)", result),
        None => println!("200u8 * 2 = None (溢出检测)")
    }
    
    match 100u8.checked_mul(2) {
        Some(result) => println!("100u8 * 2 = {} (成功)", result),
        None => println!("100u8 * 2 = None (溢出检测)")
    }
    
    println!("\n3.4 checked 除法示例 (检测除零):");
    match 10u8.checked_div(0) {
        Some(result) => println!("10u8 / 0 = {} (成功)", result),
        None => println!("10u8 / 0 = None (除零检测)")
    }
    
    match 10u8.checked_div(2) {
        Some(result) => println!("10u8 / 2 = {} (成功)", result),
        None => println!("10u8 / 2 = None (异常)")
    }
    
    // 实用的错误处理模式
    println!("\n3.5 实用的错误处理模式:");
    let a = 250u8;
    let b = 10u8;
    
    let safe_result = a.checked_add(b)
        .and_then(|sum| sum.checked_mul(2))
        .unwrap_or_else(|| {
            println!("   警告：计算过程中发生溢出，使用默认值");
            0
        });
    
    println!("安全链式计算: ({} + {}) * 2 = {}", a, b, safe_result);
    
    println!("   ✓ Checked模式提供最安全的溢出检测，适用于关键计算");
    println!("==================================================\n");
}

/// 演示 Saturating 饱和模式
fn demonstrate_saturating_arithmetic() {
    println!("4. Saturating 饱和模式 - 溢出时保持边界值");
    println!("   结果超出范围时，会\"饱和\"到类型的最大值或最小值");
    
    println!("\n4.1 saturating 加法示例:");
    let max_u8 = u8::MAX;  // 255
    let result1 = max_u8.saturating_add(1);    // 255 + 1 = 255 (饱和到最大值)
    let result2 = max_u8.saturating_add(100);  // 255 + 100 = 255 (饱和到最大值)
    
    println!("u8::MAX ({}) + 1 = {} (饱和到最大值)", max_u8, result1);
    println!("u8::MAX ({}) + 100 = {} (饱和到最大值)", max_u8, result2);
    
    println!("\n4.2 saturating 减法示例:");
    let min_u8 = u8::MIN;  // 0
    let result3 = min_u8.saturating_sub(1);    // 0 - 1 = 0 (饱和到最小值)
    let result4 = min_u8.saturating_sub(50);   // 0 - 50 = 0 (饱和到最小值)
    
    println!("u8::MIN ({}) - 1 = {} (饱和到最小值)", min_u8, result3);
    println!("u8::MIN ({}) - 50 = {} (饱和到最小值)", min_u8, result4);
    
    println!("\n4.3 有符号整数 saturating 示例:");
    let max_i8 = i8::MAX;  // 127
    let result5 = max_i8.saturating_add(10);   // 127 + 10 = 127 (饱和)
    let result6 = max_i8.saturating_add(200i16 as i8);  // 127 + 200 = 127 (饱和)
    
    println!("i8::MAX ({}) + 10 = {} (饱和到最大值)", max_i8, result5);
    println!("i8::MAX ({}) + 200 = {} (饱和到最大值)", max_i8, result6);
    
    let min_i8 = i8::MIN;  // -128
    let result7 = min_i8.saturating_sub(10);   // -128 - 10 = -128 (饱和)
    let result8 = min_i8.saturating_sub(200i16 as i8);  // -128 - 200 = -128 (饱和)
    
    println!("i8::MIN ({}) - 10 = {} (饱和到最小值)", min_i8, result7);
    println!("i8::MIN ({}) - 200 = {} (饱和到最小值)", min_i8, result8);
    
    println!("\n4.4 saturating 乘法示例:");
    let result9 = 200u8.saturating_mul(2);   // 200 * 2 = 255 (饱和到最大值)
    let result10 = 50u8.saturating_mul(2);   // 50 * 2 = 100 (正常)
    
    println!("200u8 * 2 = {} (饱和到u8::MAX)", result9);
    println!("50u8 * 2 = {} (正常结果)", result10);
    
    // 饱和模式在范围调整中的应用
    println!("\n4.5 实用的范围限制示例:");
    let values = [250u16, 260u16, 270u16, 280u16];
    println!("将u16值安全转换为u8范围:");
    
    for &val in &values {
        let safe_u8 = if val > u8::MAX as u16 {
            u8::MAX
        } else {
            val as u8
        };
        println!("   {} -> {} (手动限制) 或使用saturating方法", val, safe_u8);
    }
    
    println!("   ✓ Saturating模式确保值永远在有效范围内，适用于音频、图像处理");
    println!("==================================================\n");
}

/// 三种模式的对比分析
fn demonstrate_comparison_analysis() {
    println!("5. 三种溢出处理模式对比分析");
    println!("   使用相同的溢出场景来展示三种模式的不同行为");
    
    let test_cases = [
        (u8::MAX, 1u8, "u8::MAX + 1"),
        (u8::MAX, 10u8, "u8::MAX + 10"),
        (u8::MIN, 1u8, "u8::MIN - 1"),
        (200u8, 2u8, "200u8 * 2"),
    ];
    
    println!("\n对比表格:");
    println!("{:<15} {:<12} {:<12} {:<12}", "计算", "Wrapping", "Checked", "Saturating");
    println!("{}", "=".repeat(60));
    
    for (a, b, desc) in test_cases.iter() {
        if desc.contains("*") {
            let wrapping = a.wrapping_mul(*b);
            let checked = match a.checked_mul(*b) {
                Some(val) => val.to_string(),
                None => "None".to_string(),
            };
            let saturating = a.saturating_mul(*b);
            
            println!("{:<15} {:<12} {:<12} {:<12}", desc, wrapping, checked, saturating);
        } else if desc.contains("-") {
            let wrapping = a.wrapping_sub(*b);
            let checked = match a.checked_sub(*b) {
                Some(val) => val.to_string(),
                None => "None".to_string(),
            };
            let saturating = a.saturating_sub(*b);
            
            println!("{:<15} {:<12} {:<12} {:<12}", desc, wrapping, checked, saturating);
        } else {
            let wrapping = a.wrapping_add(*b);
            let checked = match a.checked_add(*b) {
                Some(val) => val.to_string(),
                None => "None".to_string(),
            };
            let saturating = a.saturating_add(*b);
            
            println!("{:<15} {:<12} {:<12} {:<12}", desc, wrapping, checked, saturating);
        }
    }
    
    println!("\n各模式特点分析:");
    println!("📊 Wrapping (环绕):");
    println!("   - 永远不会失败，但结果可能意外");
    println!("   - 适用：位运算、哈希函数、加密算法");
    println!("   - 性能：最高（无额外检查）");
    
    println!("\n🔍 Checked (检查):");
    println!("   - 最安全，明确指出溢出情况");
    println!("   - 适用：关键计算、用户输入验证");
    println!("   - 性能：中等（需要检查+Option处理）");
    
    println!("\n🎯 Saturating (饱和):");
    println!("   - 保证结果在有效范围内");
    println!("   - 适用：音频处理、图像处理、UI坐标");
    println!("   - 性能：中等（需要范围检查）");
    
    println!("==================================================\n");
}

/// 实际应用场景演示
fn demonstrate_real_world_applications() {
    println!("6. 实际应用场景演示");
    
    println!("\n6.1 音频处理场景 - 使用 Saturating");
    println!("   音频采样值需要保持在有效范围内，避免削波失真");
    
    // 模拟16位音频采样处理
    fn process_audio_sample(sample: i16, gain: i16) -> i16 {
        // 使用饱和运算确保音频不会削波
        sample.saturating_mul(gain / 100)
    }
    
    let samples = [1000i16, 20000i16, -15000i16, 32000i16];
    let gain = 150i16; // 150% 增益
    
    println!("原始采样值 -> 处理后 ({}% 增益):", gain);
    for &sample in &samples {
        let processed = process_audio_sample(sample, gain);
        println!("   {:6} -> {:6}", sample, processed);
    }
    
    println!("\n6.2 网络数据包处理 - 使用 Checked");
    println!("   网络协议中的长度字段需要严格验证");
    
    // 模拟网络包长度验证
    fn validate_packet_length(header_len: u16, payload_len: u16) -> Result<u16, &'static str> {
        header_len.checked_add(payload_len)
            .ok_or("数据包长度溢出")
    }
    
    let test_packets = [(20u16, 1400u16), (40u16, 65500u16), (100u16, 65500u16)];
    
    for (header, payload) in test_packets.iter() {
        match validate_packet_length(*header, *payload) {
            Ok(total) => println!("   包长度: {} + {} = {} 字节 ✓", header, payload, total),
            Err(msg) => println!("   包长度: {} + {} = {} ✗", header, payload, msg),
        }
    }
    
    println!("\n6.3 游戏得分系统 - 使用 Saturating");
    println!("   游戏得分有上限，超过时保持最高分");
    
    // 模拟游戏得分系统
    fn add_score(current_score: u32, points: u32) -> u32 {
        const MAX_SCORE: u32 = 999999;
        current_score.saturating_add(points).min(MAX_SCORE)
    }
    
    let mut player_score = 990000u32;
    let score_additions = [5000u32, 10000u32, 15000u32];
    
    println!("初始得分: {}", player_score);
    for &points in &score_additions {
        player_score = add_score(player_score, points);
        println!("   +{} -> 当前得分: {}", points, player_score);
    }
    
    println!("\n6.4 计数器实现 - 使用 Wrapping");
    println!("   循环计数器需要在达到最大值后重新开始");
    
    // 模拟循环计数器（如时钟、ID生成器）
    struct CyclicCounter {
        value: u8,
        max: u8,
    }
    
    impl CyclicCounter {
        fn new(max: u8) -> Self {
            CyclicCounter { value: 0, max }
        }
        
        fn next(&mut self) -> u8 {
            let current = self.value;
            if self.value == self.max {
                self.value = 0;
            } else {
                self.value += 1;
            }
            current
        }
    }
    
    let mut counter = CyclicCounter::new(3);
    print!("循环计数器 (0-3): ");
    for _ in 0..8 {
        print!("{} ", counter.next());
    }
    println!();
    
    println!("==================================================\n");
}

/// 最佳实践建议
fn demonstrate_best_practices() {
    println!("7. 最佳实践建议");
    
    println!("\n7.1 选择合适的溢出处理策略:");
    println!("   🎯 根据应用场景选择:");
    println!("      - 关键计算 -> Checked (安全第一)");
    println!("      - 音频/图像 -> Saturating (范围限制)");  
    println!("      - 位运算/哈希 -> Wrapping (性能优先)");
    
    println!("\n7.2 防御性编程模式:");
    
    // 示例1: 安全的用户输入处理
    fn safe_string_repeat(text: &str, count: usize) -> Option<String> {
        // 检查是否会导致内存溢出
        let len = text.len();
        len.checked_mul(count)?; // 提前检查
        
        Some(text.repeat(count))
    }
    
    let test_text = "Hello ";
    match safe_string_repeat(test_text, 5) {
        Some(result) => println!("   安全字符串重复: \"{}\" * 5 = \"{}\"", test_text.trim(), result.trim()),
        None => println!("   安全字符串重复: 参数会导致溢出，拒绝执行"),
    }
    
    // 示例2: 边界检查辅助函数
    fn ensure_u8_range(value: i32) -> Result<u8, String> {
        if value < 0 {
            Err(format!("值 {} 小于 u8 最小值 0", value))
        } else if value > u8::MAX as i32 {
            Err(format!("值 {} 大于 u8 最大值 {}", value, u8::MAX))
        } else {
            Ok(value as u8)
        }
    }
    
    let test_values = [-10i32, 100i32, 300i32];
    for &val in &test_values {
        match ensure_u8_range(val) {
            Ok(safe_val) => println!("   范围检查: {} -> {} (u8) ✓", val, safe_val),
            Err(msg) => println!("   范围检查: {} ✗ - {}", val, msg),
        }
    }
    
    println!("\n7.3 性能考虑:");
    println!("   📈 性能排序: wrapping > saturating ≈ checked");
    println!("   💡 在热点代码中考虑性能影响");
    println!("   🔧 使用 #[cfg(debug_assertions)] 在debug模式启用额外检查");
    
    println!("\n7.4 代码可读性:");
    println!("   📝 明确表达意图:");
    println!("      - 使用具体的方法名 (wrapping_add 而不是 +)");
    println!("      - 添加注释说明为什么选择特定的溢出处理方式");
    println!("      - 在API设计中明确溢出行为");
    
    println!("\n7.5 测试建议:");
    println!("   🧪 测试边界情况:");
    println!("      - 类型的最大值和最小值");
    println!("      - 溢出和下溢情况");
    println!("      - 预期的饱和或环绕行为");
    
    // 示例：边界测试函数
    fn test_boundary_addition() {
        println!("\n   边界测试示例:");
        
        // 测试最大值边界
        let max_test = u8::MAX.checked_add(1);
        println!("      u8::MAX + 1 = {:?} (应该是 None)", max_test);
        
        // 测试最小值边界  
        let min_test = u8::MIN.checked_sub(1);
        println!("      u8::MIN - 1 = {:?} (应该是 None)", min_test);
        
        // 测试正常情况
        let normal_test = 100u8.checked_add(50);
        println!("      100u8 + 50 = {:?} (应该是 Some(150))", normal_test);
    }
    
    test_boundary_addition();
    
    println!("==================================================\n");
}
